Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager / Image Compression Manager Reference

Image Compression Manager Functions / Working With Images

ConvertImage

The ConvertImage function allows your application to convert the format of a compressed image. This function is essentially equivalent to decompressing
and recompressing the image.

pascal OSErr ConvertImage (ImageDescriptionHandle srcDD, 
                           Ptr srcData, short colorDepth,
                           CTabHandle clut, CodecQ accuracy,
                           CodecQ quality, CodecType cType,
                           CodecComponent codec,
                           ImageDescriptionHandle dstDD, 
                           Ptr dstData);

srcDD

Contains a handle to the image description structure that describes the compressed image.

srcData

Points to the compressed image data. This pointer must contain a 32-bit clean address.

colorDepth

Specifies the depth at which the recompressed image is likely to be viewed. Decompressors may use this as an indication of the color or grayscale resolution of the compressed image. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function (see "Getting Information About Compressor Components" on page 3-56 for more information on the GetCodecInfo function).

clut

Contains a handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the clut parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to nil, the compressor uses the color lookup table from the source image description structure.

accuracy

Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See "Compression Quality Constants" on page 3-52 for valid values. (For a good display of still images, you should specify at least the codecHighQuality constant.)

quality

Specifies the desired compressed image quality. See "Compression Quality Constants" on page 3-52 for valid values. Use the following value:

codecHighQuality

Specifies high-quality image reproduction. This value should correspond to the highest image quality that can be achieved with reasonable performance.

cType

Specifies a compressor type. You must set this parameter to a
valid compressor type. See Table 3-3 on page 3-59 for a list of the available compressor types.

codec

Contains a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anyCodec, the Image Compression Manager chooses the first compressor it finds of the specified type.

dstDD

Contains a handle that is to receive a formatted image description structure. The Image Compression Manager resizes this handle for the returned image description structure. Your application should store this image description with the compressed image data.

dstData

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function (described on page 3-63). The Image Compression Manager places the actual size of the compressed image into the dataSize field of the image description referred to by the dstDD parameter. This pointer must contain a 32-bit clean address.

DESCRIPTION

During the decompression operation, the decompressor uses the srcDD, srcData, and accuracy parameters. During the subsequent compression operation, the compressor uses the colorDepth, clut, cType, codec, quality, dstDD, and dstData parameters.

RESULT CODES

noErr	0	No error
paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
noCodecErr	-8961	The Image Compression Manager could not find the specified compressor